home *** CD-ROM | disk | FTP | other *** search
/ CD Concept 6 / CD Concept 06.iso / mac / UTILITAIRE / Universal TCL 1.1.3 v3.1 / READ THIS OR CRASH < prev    next >
Encoding:
Text File  |  1995-02-02  |  8.1 KB  |  179 lines  |  [TEXT/MMCC]
  1. Think Class Library v1.1.3 Porting Kit v3.1 ⌐1993-1995 Yellow Shark AB
  2.  
  3. README - the manual
  4.  
  5. Welcome to version 3.1 of the TCL 1.1.3 porting package. This package will 
  6. allow you to port your TCL 1.1.3 applications, and your TCL 1.1.3 library, 
  7. to Metrowerks CodeWarrior, and probably other C++ compilers found on the 
  8. Macintosh, and also to compile the TCL for Power Macintosh.
  9.  
  10. Before you use the software included, be sure to read the license at the 
  11. end of this document, and agree with it. IF YOU DON'T AGRE WITH AND ABIDE 
  12. BY THE LICENSE, YOU CANNOT USE THE INCLUDED SOFTWARE!
  13.  
  14. A side effect of the new (in 3.0) RTTI stuff is that you can use this
  15. porting kit if you want to move your TCL 1.1.3 application to TCL 2.0; 
  16. this RTTI and the Symantec TCL 2.0 RTTI look very much the same at the 
  17. macro level, so much of the work will be done for you. Then use Eric 
  18. Scouten's TCL 2.0 porting kit to compile TCL 2.0 with CodeWarrior!
  19.  
  20. This kit is produced and tested using CW5 final compilers for 68K and PPC, 
  21. and has been used on a large (>100000 line) application with good results. 
  22. You need version 2 or later of the universal headers (included in CW5)
  23.  
  24. If you're getting ready to go, this is how to do it:
  25.  
  26. 0) Read through all of the instructions before beginning. Most important, 
  27. read through the common munger instructions before starting any munging 
  28. application.
  29.  
  30. 1) Back up everything. Just to be safe.
  31.  
  32. 2) Install Symantec C++ version 6.0 on your hard disk. You only need the 
  33. TCL 1.1.3 folder, but it's easiest to grab the whole package.
  34.  
  35. 3) Run the MultiDiff application provided, applying the TCL Diff 3.0 file 
  36. provided on the Think Class Library 1.1.3 folder. The diff file 
  37. distributed only contains my additions to the TCL; therefore it's free of 
  38. Symantec copyright.
  39.  
  40. 4) Move the converted TCL 1.1.3 folder into the Pointer TCL 3.1 folder, 
  41. and place that folder somewhere convenient. Inside the CodeWarrior folder 
  42. is NOT a good idea. Rename "Think Class Library 1.1.3" to "inherited 
  43. sources".
  44.  
  45. 5) If you have used version 2.0 or 2.1 of the TCL porting package you 
  46. should build and run the retromung munger application on your project 
  47. folder. <see common munger instructions below>
  48. If you have used version 3.0 of the porting kit, you only have to replace 
  49. your copy of the munged TCL 1.1.3 folder and the " new source" folder, 
  50. since the mungers have not changed.
  51.  
  52. 6) Copy the file TCL CLASSLIST into the Mungers folder and rename it 
  53. CLASSLIST. (No period in the name) Then run the buildclasslist munger on 
  54. your project folder.
  55.  
  56. 7) <optionally> run the disinherit munger to expand "inherited" into the 
  57. actual superclass name. This requires a complete CLASSLIST from the step 
  58. above.
  59.  
  60. 8) Run the insertmacros munger on your project folder. This will insert 
  61. TCL_DECLARE_CLASS and TCL_DEFINE_CLASS macros in your source. It will also 
  62. change struct classes to real class classes.
  63.  
  64. 9) Run the deconflict munger on your project folder. This will change all 
  65. occurences of GetItem to the proper method name or toolbox call, as well 
  66. as fix some other similar problems (it does this by counting arguments in 
  67. the argument list)
  68.  
  69. 10) <optionally> run the headerprot munger on your project folder. This 
  70. will insert multiple-inclusion protection using the __HEADER_FILE__ 
  71. convention. CodeWarrior supports #pragma once, but some other compilers 
  72. don't.
  73.  
  74. 11) Move your project file to somewhere handy. Create a CodeWarrior 
  75. project file by running Convert*Projects, or by adding your files to the 
  76. included project files. Remember the appropriate runtime libraries! Add 
  77. the Pointer TCL folder from step 4 to the project access path list.
  78. The folder containing both "inherited" and "new" sources should be the 
  79. one added, not just the converted "inherited sources" folder. You should 
  80. remove or convert any assembly files you may use; the TCL assembly files 
  81. are no longer needed. The provided 68K project is segmented to fit into 
  82. the near code model, but you need far data. The segmentation is also 
  83. sub-optimal.
  84.  
  85. 12) Compile your project. Where you get complaints about type mismatches, 
  86. there may be one of several problems:
  87. -In version 2.0 of the Universal Headers, WindowPtr and WindowPeek have 
  88. been replaced with a WindowRef type.
  89. -Using universal headers, you have to create universal procedure pointers 
  90. wherever you pass a ProcPtr to the toolbox. For instance:
  91.  
  92.     StandardGetFile(MyFileFilter, numTypes, typeList, &reply);
  93.  
  94. would become:
  95.  
  96.     static FileFilterUPP MyFileFilterUPP = NewFileFilterProc(MyFileFilter);
  97.     StandardGetFile(MyFileFilterUPP, numTypes, typeList, &reply);
  98.  
  99. This is by far the easiest way to allocate and handle UPPs, and works for 
  100. both 68K and PowerPC code. For more info, see the comp.sys.mac.programmer
  101. FAQ, available on http://www.nada.kth.se/~d88-jwa/mac-faq.html or via FTP on
  102. ftp.nada.kth.se:pub/hacks/mac-faq/CSMP_PD_FAQ
  103. Another good reference is New Inside Macintosh: PowerPC System Software
  104.  
  105. You may want to use #pragma options align=mac68k around data structures you 
  106. write to disk or resources, to use the faster PowerPC alignment when 
  107. compiling for PowerPC. The new TCL sources do this, surrounded by the
  108. preprocessor symbol NOPRAGMAALIGN. Unfortunately, the Universal Headers 
  109. included with CW5 will not support anything but plain 68k aligmnent when 
  110. compiling for the 68k.
  111.  
  112. You may have to force references to classes you create using new_by_name by 
  113. calling member() on them, or something similar. This is because of a slight 
  114. feature in the CodeWarrior linker, where it decides an object is not 
  115. referenced when all you do with it is to create it static; despite the fact 
  116. that the object constructor has side effects.
  117.  
  118.  
  119. 13) Congratulations! You're now done! Unless you're using a library that's 
  120. only available for the 68K Mac, in which case you need to get an upgrade 
  121. from your supplier. I can't do everything for you :-)
  122.  
  123.  
  124. EXCEPTION HANDLING
  125.  
  126. The exception handling package is good enough, but not perfect. Most 
  127. notably, if you have more than one exception handler within a function, all 
  128. but one muse change their TRY clause to TRY_MULTIPLE. You cannot use RETRY 
  129. within a TRY_MULTIPLE clause, but if you do, no warning may be given. Watch 
  130. out!
  131.  
  132. The exception library can be rewritten using switch() instead of goto, and 
  133. if I ever get more time, I will do this for a X.Y version of the porting 
  134. kit. However, it IS usable as it is; we're shipping commercial applications 
  135. with it, so don't hold your breath for the new version.
  136.  
  137.  
  138. INSTRUCTIONS FOR RUNNING THE MUNGER APPLICATIONS:
  139.  
  140. All the mungers require you to first build the munglib.lib and liblib.lib 
  141. libraries. When you run them, most of them look for a file called 
  142. "CLASSLIST" in the folder they're in. They all do their work on whatever 
  143. is in the folder or alias called TO MUNG in the same folder as the munger 
  144. application; this includes sub-folders of TO MUNG. It *will* follow 
  145. aliases recursively, so remove any pointing to code you don't want 
  146. munged!
  147.  
  148. All mungers are PowerPC projects. If you run on a 68K Mac, upgrade :-) 
  149. Seriously, you can change liblib.lib to include the relevant 68K libraries, 
  150. re-build munglib.lib and the mungers with the 68K compiler. That's why we 
  151. included liblib.lib instead of the libraries in the munger applications! 
  152. You need ANSI, SIOUX, MacOS.lib and maybe SANE.
  153.  
  154.  
  155. CREDITS
  156.  
  157. Most of the grunt work for this port was made by Bo Lindbergh for me. 
  158. He may be reached as d88-bli@nada.kth.se. I may be reached as 
  159. h+@metrowerks.com, but I cannot promise to support this port more than on 
  160. my spare time. THIS IS NOT A METROWERKS OFFERING.
  161.  
  162. We would appreciate if you mailed comments, suggestions, and products 
  163. relating to or created by this port package to us.
  164.  
  165.  
  166. LICENSE
  167.  
  168. This software is provided as a public service free of charge. It is 
  169. copyrighted ⌐1994 Yellow Shark AB, published in Stockholm, Sweden. 
  170. Permission is granted to use this software and derivatives you make 
  171. thereof, provided that any such use is AT YOUR OWN RISK and that you agree 
  172. to, in all cases, take full responsibility for any malfunction or defect 
  173. in the software or the results thereof.
  174.  
  175. IF YOU CANNOT OR WILL NOT AGREE TO THIS LICENSE, OR YOUR LOCAL LAWS DO NOT 
  176. ALLOW THIS REDUCTION OF YELLOW SHARK ABs' LIABILITY TO ZERO, YOU ARE NOT 
  177. ALLOWED TO USE THE SOFTWARE.
  178.  
  179.